home *** CD-ROM | disk | FTP | other *** search
/ Workbench Add-On / Workbench Add-On - Volume 1.iso / Dev / Amiga-E / E_v3.2a_extras / PdSrc / Lang / Yax / yax.doc < prev    next >
Lisp/Scheme  |  1992-09-02  |  7KB  |  225 lines
  1.  
  2.         +---------------------------------------+
  3.         |                                       |
  4.         |       Amiga YAX Interpreter v1.1      |
  5.         |                                       |
  6.         |            (c) 1992/93 $#%!           |
  7.         |              M A N U A L              |
  8.         |                                       |
  9.         +---------------------------------------+
  10.  
  11. /* v1.2 now includes as mass of new functions! look at end of this doc. */
  12.  
  13.             1. Introduction
  14.             2. The Language
  15.             3. Built-in Functions
  16.  
  17.         +---------------------------------------+
  18.         |    1. Introduction            |
  19.         +---------------------------------------+
  20.  
  21. update from v0.x/1.0 to 1.1:
  22. bug fixes:
  23. - negative number division failed!
  24. - box accepted illegal values
  25.  
  26. update from v1.1 to 1.2:
  27. - new functions, see below.
  28.  
  29. YAX stands for "Yet Another Instruction Code Set", as the author couldn't
  30. think of better name. YAX is a procedural language with LISP-syntax and
  31. evaluation, as well as somewhat lambda function application.
  32.  
  33. In this manual it is assumed the reader possesses knowledge of other
  34. languages, as all 'obvious' explanations are left out. Readers for whom
  35. YAX would be their first programming language are advised to read
  36. a standard text on the subject  8-).
  37.  
  38.         +---------------------------------------+
  39.         |    2. The Language            |
  40.         +---------------------------------------+
  41.  
  42. Structure.
  43. The basic building block of a YAX program is called a term.
  44. Examples of terms are:
  45.  
  46. integer constants:    1 2 100 -1
  47. string constants:    'a' 'hi folks!'
  48. variables:        a count
  49. function calls:        (+ 1 2) (* 3 (- 4 5))
  50.  
  51. a function call is a list '()' with as first item the name of the
  52. function to be applied, followed by its arguments. With few execeptions,
  53. arguments to functions are again terms, so expressions may be built
  54. to infinite complexity. The main task of the interpreter is to
  55. evaluate these terms recursively.
  56.  
  57. Format.
  58. between any two lexical elements, any number of spaces, tabs and linefeeds
  59. may be placed. Comments start with '/*' and end with '*/', may extend
  60. over several lines, and may be nested. following two statements are equal:
  61.  
  62. (if(eq a 1)(for b 1 10(write'blabla')))       /* ugly */
  63.  
  64. (if (eq a 1)
  65.   (for b 1 10 (write 'blabla'))               /* better */
  66. )
  67.  
  68.  
  69.         +---------------------------------------+
  70.         |    3. Built-in Functions        |
  71.         +---------------------------------------+
  72.  
  73. If not explicitly stated, functions return 0. type of arguments:
  74.  
  75. <term>        any term
  76. <iterm>        term that evaluates to integer
  77. <sterm>        term that evaluates to string
  78. <var>        term that is a variable
  79. <svar>        term that is a string variable
  80. <func>        term that evaluates to a function
  81. ...        any number of terms of the same type may follow
  82.  
  83.                            --> INTEGER MATH <--
  84.  
  85. (add <iterm> ...)     or    (+ <iterm> ...)
  86. (sub <iterm> ...)     or    (- <iterm> ...)
  87. (mul <iterm> ...)     or    (* <iterm> ...)
  88. (div <iterm> ...)     or    (/ <iterm> ...)
  89.  
  90. (and <iterm> ...)
  91. (or <iterm> ...)
  92. (not <iterm>)
  93.  
  94. (eq <iterm> ...)
  95. (uneq <iterm> <iterm>)
  96. (smaller <iterm> <iterm>)
  97. (greater <iterm> <iterm>)
  98.  
  99. These functions perform the functions you'd expect them to do.
  100. All boolean logic functions return true (-1) or false (0). and/or/not
  101. work as logical as well as bitwise operators.
  102. except for the last three, all functions handle any number of arguments,
  103. i.e.  (eq 10 (+ 1 2 3 4) (* 2 5))  is a valid term.
  104.  
  105.                          --> PROGRAM STRUCTURE <--
  106.  
  107. (for <var> <iterm> <iterm> <term> ...)
  108. (if <boolexp> <ifterm> <elseterm>)
  109.   /* also returns value of term */
  110. (do <term> ...)
  111. (select <iterm> <term> ...)
  112.   /* <iterm> is matched agains even items of <term>s, and 
  113.      corresponding odd <term> is executed */
  114. (while <term> <term> ...)
  115. (until <term> <term> ...)
  116. (set <var> <term>)
  117.  
  118. (defun <var> (<var> ...) <term> ...)
  119. (lambda (var ...) <term> ...)
  120.    /* returns function as value (may only be used in (set) and (apply) */
  121. (apply <func> <term> ...)
  122.  
  123. (array <var> <iterm>)
  124. (string <var>)
  125.  
  126.  
  127.                            --> INPUT OUTPUT <--
  128.  
  129. (write <term> ...)
  130. (locate <iterm> <iterm>)
  131. (cls)
  132. (window <iterm> <iterm> <iterm> <iterm> <sterm>)
  133.  
  134. (tell <sterm>)            open a file for writing
  135. (told)                close file
  136. (see <sterm>)            open a file for reading
  137. (seen)                close file
  138. (filelen <sterm>)        get filelength
  139.  
  140. (readint)            read an integer
  141. (read <svar>)            read a string
  142. (get)                read one character
  143. (put <iterm>)            write one character
  144.  
  145. (dump)                show all variables
  146.  
  147.  
  148.                              --> GRAPHICS <--
  149.  
  150. (line <iterm> <iterm> <iterm> <iterm> <iterm>)
  151. (plot <iterm> <iterm> <iterm>)
  152. (box <iterm> <iterm> <iterm> <iterm> <iterm>)
  153. (text <iterm> <iterm> <iterm> <iterm> <sterm>)
  154. (mousex), (mousey)        intuition
  155. (mouse)                non-intuition
  156.  
  157.  
  158.  
  159. NEW IN VERSION 1.2:
  160. - changes to existing functions:
  161.     (>) as equivalent for (greater)
  162.     (<) as equivalent for (smaller)
  163.     (array <var> <size> <iterm> ...)    /* inits array with <iterm>s (opt) */
  164.     (set <stringvar> <sterm>)
  165. - additional functions:
  166.   math etc.:
  167.     (abs <iterm>)
  168.     (mod <iterm> <iterm>)        /* (mod 20 3) => 2 */
  169.     (eor <iterm> ...)
  170.     (swap <var> <var>)            /* currently vars only */
  171.     (power <iterm> <iterm>)        /* (power 2 5) => 32 */
  172.     (inc <var>)
  173.     (dec <var>)
  174.   system:
  175.     (kick <iterm>)            /* (if (kick 37) ... ) */
  176.     (exit)
  177.   control:
  178.     (when <iterm> <term> ...        /* (if <bterm> (do <term> ...)  */
  179.              else <term> ...)        /*             (do <term> ...)) */
  180.   input/output:
  181.     (hex <iterm>)            /* writes num in hexadecimal */
  182.   intuition:
  183.     (req <sterm> <sterm> <sterm>)    /* (req 'YAX req' 'choose:' 'a|b|c') */
  184.     (screen w h d flags title)        /* opens screen */
  185.     (win x y w h IDCMP flags title)    /* opens gfx-only window and closes
  186.                        any previous w. if (screen) was
  187.                                            used, (win) opens on it */
  188.     (gadget id x y width title)         /* makes gadget on cur. window */
  189.     (message)                /* Wait()s and returns IDCMP */
  190.     (gadid)                /* returns gadnum in event */
  191.  
  192.   NOTE: - now that there's (win) and (screen), graphics and intuition
  193.           functions should not be used on windows opened with (window)
  194.           (these are for stdio only), it will be possible however to use
  195.           graphics functions on them for backward compatability with 1.1.
  196.         - (req) is 2.04+, all others are 1.2+
  197.  
  198.  
  199. POSSIBLE ENHANCEMENTS:
  200. - true lambda's for function calls
  201. - (cond)
  202.  
  203. ben:
  204. - string commands
  205. - run another yax prog from yax code
  206. - (see) twice --> problems? better file support.
  207. - yax compiler (to E)
  208. - (/) moet weer 32bit. + check div by zero.
  209. - !! select break mogelijkheid!!
  210.  
  211. BUGS:
  212. - array uitlezen een index te weinig
  213.  
  214.  
  215. ETC: check ben's correspondentie, 24 april '93
  216.  
  217. >> YAX divide algorithm using YAXv1.0's unsigned 32 bit division:
  218. >> if (denominator)
  219. >>   answer =  (abs(numerator)/abs(denominator))
  220. >>   if (numerator eor denominator < 0)
  221. >>     answer = -answer
  222. >> otherwise
  223. >>   ERROR_DIV_BY_ZERO
  224.  
  225.